home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / tclvars.n < prev    next >
Encoding:
Text File  |  1995-02-22  |  5.5 KB  |  144 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) tclvars.n 1.3 95/02/22 14:27:30
  9. '\" 
  10. .so man.macros
  11. .HS tclvars tcl
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. tclvars \- Variables used by Tcl
  16. .BE
  17.  
  18. .SH DESCRIPTION
  19. .PP
  20. The following global variables are created and managed automatically
  21. by the Tcl library.  Except where noted below, these variables should
  22. normally be treated as read-only by application-specific code and by users.
  23. .TP
  24. \fBenv\fR
  25. .br
  26. This variable is maintained by Tcl as an array
  27. whose elements are the environment variables for the process.
  28. Reading an element will return the value of the corresponding
  29. environment variable.
  30. Setting an element of the array will modify the corresponding
  31. environment variable or create a new one if it doesn't already
  32. exist.
  33. Unsetting an element of \fBenv\fR will remove the corresponding
  34. environment variable.
  35. Changes to the \fBenv\fR array will affect the environment
  36. passed to children by commands like \fBexec\fR.
  37. If the entire \fBenv\fR array is unset then Tcl will stop
  38. monitoring \fBenv\fR accesses and will not update environment
  39. variables.
  40. .TP
  41. \fBerrorCode\fR
  42. After an error has occurred, this variable will be set to hold
  43. additional information about the error in a form that is easy
  44. to process with programs.
  45. \fBerrorCode\fR consists of a Tcl list with one or more elements.
  46. The first element of the list identifies a general class of
  47. errors, and determines the format of the rest of the list.
  48. The following formats for \fBerrorCode\fR are used by the
  49. Tcl core; individual applications may define additional formats.
  50. .RS
  51. .TP
  52. \fBARITH\fI code msg\fR
  53. .VS
  54. This format is used when an arithmetic error occurs (e.g. an attempt
  55. to divide by zero in the \fBexpr\fR command).
  56. \fICode\fR identifies the precise error and \fImsg\fR provides a
  57. human-readable description of the error.  \fICode\fR will be either
  58. DIVZERO (for an attempt to divide by zero),
  59. DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
  60. IOVERFLOW (for integer overflow),
  61. OVERFLOW (for a floating-point overflow),
  62. or UNKNOWN (if the cause of the error cannot be determined).
  63. .VE
  64. .TP
  65. \fBCHILDKILLED\fI pid sigName msg\fR
  66. This format is used when a child process has been killed because of
  67. a signal.  The second element of \fBerrorCode\fR will be the
  68. process's identifier (in decimal).
  69. The third element will be the symbolic name of the signal that caused
  70. the process to terminate; it will be one of the names from the
  71. include file signal.h, such as \fBSIGPIPE\fR.
  72. The fourth element will be a short human-readable message
  73. describing the signal, such as ``write on pipe with no readers''
  74. for \fBSIGPIPE\fR.
  75. .TP
  76. \fBCHILDSTATUS\fI pid code\fR
  77. This format is used when a child process has exited with a non-zero
  78. exit status.  The second element of \fBerrorCode\fR will be the
  79. process's identifier (in decimal) and the third element will be the exit
  80. code returned by the process (also in decimal).
  81. .TP
  82. \fBCHILDSUSP\fI pid sigName msg\fR
  83. This format is used when a child process has been suspended because
  84. of a signal.
  85. The second element of \fBerrorCode\fR will be the process's identifier,
  86. in decimal.
  87. The third element will be the symbolic name of the signal that caused
  88. the process to suspend; this will be one of the names from the
  89. include file signal.h, such as \fBSIGTTIN\fR.
  90. The fourth element will be a short human-readable message
  91. describing the signal, such as ``background tty read''
  92. for \fBSIGTTIN\fR.
  93. .TP
  94. \fBNONE\fR
  95. .br
  96. This format is used for errors where no additional information is
  97. available for an error besides the message returned with the
  98. error.  In these cases \fBerrorCode\fR will consist of a list
  99. containing a single element whose contents are \fBNONE\fR.
  100. .TP
  101. \fBPOSIX \fIerrName msg\fR
  102. .VS
  103. If the first element of \fBerrorCode\fR is \fBPOSIX\fR, then
  104. the error occurred during a POSIX kernel call.
  105. .VE
  106. The second element of the list will contain the symbolic name
  107. of the error that occurred, such as \fBENOENT\fR; this will
  108. be one of the values defined in the include file errno.h.
  109. The third element of the list will be a human-readable
  110. message corresponding to \fIerrName\fR, such as
  111. ``no such file or directory'' for the \fBENOENT\fR case.
  112. .PP
  113. To set \fBerrorCode\fR, applications should use library
  114. procedures such as \fBTcl_SetErrorCode\fR and
  115. .VS
  116. \fBTcl_PosixError\fR,
  117. .VE
  118. or they may invoke the \fBerror\fR command.
  119. If one of these methods hasn't been used, then the Tcl
  120. interpreter will reset the variable to \fBNONE\fR after
  121. the next error.
  122. .RE
  123. .TP
  124. \fBerrorInfo\fR
  125. After an error has occurred, this string will contain one or more lines
  126. identifying the Tcl commands and procedures that were being executed
  127. when the most recent error occurred.
  128. Its contents take the form of a stack trace showing the various
  129. nested Tcl commands that had been invoked at the time of the error.
  130. .TP
  131. \fBtcl_precision\fR
  132. .VS
  133. If this variable is set, it must contain a decimal number giving the
  134. number of significant digits to include when converting floating-point
  135. values to strings.
  136. If this variable is not set then 6 digits are included.
  137. 17 digits is ``perfect'' for IEEE floating-point in that it allows
  138. double-precision values to be converted to strings and back to
  139. binary with no loss of precision.
  140. .VE
  141.  
  142. .SH KEYWORDS
  143. arithmetic, error, environment, POSIX, precision, subprocess, variables
  144.